
<h1 class='med'>Documentation <img src='/images/exclaim_med_up.png' /></h1>

	<p>Learn, DAMN IT!  This documentation will cover the following:</p>
	
	<ul>
		<li><a href='#setup'>Setup</a></li>
		<li><a href='#using'>Using</a></li>
		<li><a href='#advanced'>Advanced Usage</a></li>
		<li><a href='#security'>Security concerns</a></li>
	</ul>
	
	<h2 id='setup'>Setup</h2>
	
	<p>For a head start, <a href='http://javascriptmvc.googlecode.com/files/damnit_demo.html'>download</a> the code 
	from the demo.</p>
	
	<p>There are two ways to set up DamnIT:</p>
	
	<ul>
		<li><a href='#setup1'>Using the error plugin of JavaScriptMVC</a></li>
		<li><a href='#setup2'>As a standalone script</a></li>
	</ul>
	
	<h3 id='setup1'>Setting up DamnIT with JavaScriptMVC</h3>
	
	<p>DamnIT is available as <a href='http://javascriptmvc.com'>JavaScriptMVC</a>'s error plugin.  Using 
	JavaScriptMVC's error plugin lets you easily compress your application with the DamnIT 
	library.  To load DamnIT with JavaScriptMVC, all you have to do is include the error plugin.</p>
	
	<p>Setup steps:</p>
	
	<ol>
		<li>Obtain an application key</li>
		<li>Include the error plugin</li>
	</ol>
	
	<h4>Obtaining an application key:</h4>
	
	<ol>
		<li>Sign up at <a href='https://damnit.jupiterit.com'>damnit.jupiterit.com</a>.</li>
		<li>Click the link in the confirmation email.</li>
		<li>Get your Application Key on the <% if logged_in? %><a href='/instructions'>setup instructions page</a><% else %>setup instructions page<% end %>.</li>
	</ol>
	
	<h4>Including the error plugin:</h4>
	
	<p>Assuming you've correctly 
	<a href='http://javascriptmvc.com/learningcenter/tutorials/get_started.html'>set up</a> your JavaScriptMVC application, 
	the following code includes the error plugin and defines your application key.  Make
	sure you replace <span class="highlight">_APPLICATION_KEY_</span> with your application key.</p>
	
	<div class='code_caption'>
	<pre><code>APPLICATION_KEY=<span class='string'>'<span class="highlight">_APPLICATION_KEY_</span>'</span>;
include.plugins(<span class='string'>'error'</span>);</code></pre>
	<div class='caption'>Setting up the error plugin</div>
	</div>
	<p>The error plugin only reports errors in JavaScriptMVC's production mode.</p>

	
	<h3 id='setup2'>Setting up DamnIT as a standalone script</h3>
	
	<p>Setup steps:</p>
	
	<ol>
		<li>Obtain an application key</li>
		<li>Load the DamnIT script</li>
	</ol>
	
	<h4>Obtaining an application key:</h4>
	
	<ol>
		<li>Sign up at <a href='https://damnit.jupiterit.com'>damnit.jupiterit.com</a>.</li>
		<li>Click the link in the confirmation email.</li>
		<li>Get your Application Key on the <% if logged_in? %><a href='/instructions'>setup instructions page</a><% else %>setup instructions page<% end %>.</li>
	</ol>
	
	<h4>Loading the DamnIT script:</h4>
	<p>Insert the following code into your html pages right <span class="highlight">before</span> the ending body tag (&lt;/body>).
		Replace <span class="highlight">_APPLICATION_KEY_</span> with your application key.
	
	</p>
	<div class='code_caption'>
	<pre><code>&lt;<span class='html_key'>script</span> type=<span class='string'>'text/javascript'</span> 
   src=<span class='string'>'https://damnit.jupiterit.com/damnit.js?<span class="highlight">_APPLICATION_KEY_</span>'</span>&gt;
&lt;/<span class='html_key'>script</span>&gt;</code></pre>
	<div class='caption'>Setting up the DamnIT script</div>
	</div>
	
	
	<h2 id='using'>Using</h2>
	
	<p>We'll walk through:
	
	<ul>
		<li><a href='#catching'>how to catch errors in all the browsers</a></li>
		<li><a href='#browser'>browser support for error reporting functionality</a></li>
		<li><a href='#configuring'>how to configure DamnIT for your application's needs</a></li>
	</ul>
	
	<h3 id='catching'>Catching Errors</h3>
	
	<p>IE and Mozilla support the <a href='http://www.w3schools.com/js/js_onerror.asp'>onerror</a> event, while Opera 
	and Safari do not.  Thus, DamnIT error notification works automatically in IE and Mozilla, while you have to wrap 
	your code in try...catch blocks in other browsers to add DamnIT's error notification functionality.  If you're 
	using JavaScriptMVC's <a href='http://javascriptmvc.com/learningcenter/controller/index.html'>Controller</a> 
	plugin, your code is covered across all browsers.</p>
	
	<h4>IE and Mozilla: Automatic Support</h4>
	
	<p>These browsers require no additional code in your application to catch all errors and notify you.  For many 
	apps, IE and Mozilla support is sufficient, since they make up 91% of the browser market.</p>
	
	<h4>Safari and Opera: Wrap your Code with try...catch</h4>
	
	<p>Opera and Safari don't support the onerror event, so add DamnIT functionality 
	like this:</p>
	
	<div class='code_caption'>
	<pre><code><span class='key'>try</span> { <span class='comment'>// <b>1</b></span>
   this.will.cause.an.error();
} <span class='key'>catch</span>(e) {
   ApplicationError.notify(e); <span class='comment'>// <b>2</b></span>
}</code></pre>
	<div class='caption'>Catching errors in Safari &amp; Opera</div>
	</div>

	<ol>
		<li>Place try...catch blocks around your application code.</li>
		<li>ApplicationError.notify accepts an error object and performs the same functionality as 
		the onerror event handler for IE and Mozilla: prompting the user and sending error 
		information to the DamnIT server.</li>
	</ol>
	
	<h4>DamnIT with Controller: Cross Browser Support</h4>

	<p>The easiest way to maximize DamnIT's code coverage for all browsers is to use 
	<a href='http://javascriptmvc.com/learningcenter/controller/index.html'>Controller</a> 
	to define your event handlers.  Errors within event handlers defined using 
	<a href='http://javascriptmvc.com/learningcenter/controller/index.html'>Controller</a> 
	are automatically caught and reported across all browsers.</p>

	<h3 id='browser'>Browser Support</h3>
	
<div class="table_container">
	<table cellspacing='5'>
		<tr>
			<th class='blank'>&nbsp;</th>
			<th>Onerror Support</th>
			<th>Controller Support</th>
			<th>Error Line Number and Script Name</th>
			<th class='last'>Error Stack</th>
		</tr>
		<tr>
			<th>IE</th>
			<td class='yes'>Yes</td>
			<td class='yes'>Yes</td>
			<td class='no'>No</td>
			<td class='last no'>No</td>
		</tr>
		<tr>
			<th>Firefox</th>
			<td class='yes'>Yes</td>
			<td class='yes'>Yes</td>
			<td class='yes'>Yes</td>
			<td class='last yes'>Yes</td>
		</tr>
		<tr>
			<th>Opera</th>
			<td class='no'>No</td>
			<td class='yes'>Yes</td>
			<td class='yes'>Yes</td>
			<td class='last yes'>Yes</td>
		</tr>
		<tr class='last'>
			<th>Safari</th>
			<td class='no'>No</td>
			<td class='yes'>Yes</td>
			<td class='yes'>Yes</td>
			<td class='last no'>No</td>
		</tr>
	</table>
</div>

	<h3 id='configuring'>Configuring DamnIT</h3>
	
	<p>DamnIT provides the ability to customize the contents of its user prompt or 
	to turn off the user prompt entirely.</p>
	
	<h4>Turning off user prompt</h4>
	
	<p>During beta testing, its useful to ask testers to describe their actions the preceded  the error.  
	As you move into production, you may wish to turn this functionality off.  You can do so with the 
	prompt_user option of ApplicationError's config method:</p>
	
	<div class='code_caption'>
	<pre><code>ApplicationError.config({<span class='attribute'>prompt_user:</span> false});</code></pre>
	<div class='caption'>Turning off user prompt</div>
	</div>
	
	<h4>Configuring user prompt</h4>
	
	<p>You can configure the user prompt to say what you like and stay open for as long as 
	you'd like:</p>
	
	<div class='code_caption'>
	<pre><code>ApplicationError.config({
   <span class='attribute'>prompt_text:</span> <span class='string'>'DAMN IT YOU BROKE IT!'</span>, 
   <span class='attribute'>textarea_title:</span> <span class='string'>'Please explain.'</span>, 
   <span class='attribute'>close_time:</span> 4
});</code></pre>
	<div class='caption'>Configuring user prompt</div>
	</div>
	
	<p>The above configuration creates the following user prompt:</p>
	
	<div class='image code_caption'>
		<img src='/images/documentation/prompt_config.png' />
		<div class='caption'>Modified user prompt</div>
	</div>
	
	<h2 id='advanced'>Advanced Usage</h2>
	
	<p>After you mastered the basics, you can start adding your own functionality to your DamnIT 
	notifications.  You can:</p>
	
	<ul>
		<li><a href='#adding'>Add information to your notifications</a></li>
		<li><a href='#other_purposes'>Use DamnIT notifications for other purposes</a></li>
		<li><a href='#sending'>Send custom notifications</a></li>
	</ul>
	
	<h3 id='adding'>Adding Information to your Notifications</h3>
	
	<p>You can add information to your error emails if there is something else you want to know 
	about an error.  You can do this by creating your own attributes and adding them to the 
	error object passed into ApplicationError.notify.</p>
	
	<p>For example, you might want to know the username of the person who broke your application:</p>
	
	<div class='code_caption'>
	<pre class='code_caption'><code><span class='key'>try</span> {
   this.will.cause.an.error();
} <span class='key'>catch</span>(e) {
   e.username = <span class='string'>'Brian'</span>;
   ApplicationError.notify(e);
}</code></pre>
	<div class='caption'>Adding username to the notification email</div>
	</div>

	<p>Or maybe you noticed a lot of problems in IE, but since IE doesn't provide file name 
	information in the error, you manually add it:</p>
	
	<div class='code_caption'>
	<pre><code><span class='key'>try</span> {
   this.will.cause.an.error();
} <span class='key'>catch</span>(e) {
   e.fileName = <span class='string'>'myscript.js'</span>;
   ApplicationError.notify(e);
}</code></pre>
	<div class='caption'>Adding file name manually</div>
	</div>

	<p>You'll see this information added to your email notifications.</p>
	
	<h3 id='other_purposes'>Using DamnIT for Other Purposes</h3>
	
	<p>DamnIT is a JavaScript reporting service.  It allows you to always be aware when something 
	of consequence happens in your applications.</p>
	
	<p>Beyond error notification, you can use DamnIT to notify you when a user:</p>
	
	<ul>
		<li>clicks your new drag and drop widget</li>
		<li>types something in an important input box</li>
		<li>clicks an area of the page</li>
	</ul>
	
	<p>These examples are trivial, but the point is you can use DamnIT to notify you of anything 
	that occurs in your JavaScript application.  Error notification is simply the best application 
	we've come up with so far.</p>
	
	<h3 id='sending'>Sending a Custom Notification</h3>
	
	<p>If you wish to use DamnIT for a purpose other than error reporting, you can easily create 
	your own notification functionality using ApplicationError's send method:</p>
	
	<div class='code_caption'>
	<pre><code><span class='key'>var</span> notification = <span class='key'>new</span> ApplicationError({
   <span class='attribute'>subject:</span> <span class='string'>"test"</span>,
   <span class='attribute'>content:</span> <span class='string'>"someone clicked the new widget"</span>
}); <span class='comment'>// <b>1</b></span>
notification.save(); <span class='comment'>// <b>2</b></span></code></pre>
	<div class='caption'>Creating a custom notification email</div>
	</div>
	
	<ol>
		<li>Creates a new ApplicationError instance.  Set the subject and content attributes to define what the email will contain.</li>
		<li>Sends a request to DamnIT's server to email you the subject and message content.</li>
	</ol>

	<div class='image code_caption'>
		<img src='/images/documentation/email_damnit.png' />
	<div class='caption'>Custom notification email</div>
	</div>

	<h3 id='security'>Security Concerns</h3>
	
	<h4>Data Privacy</h4>
	
	<p>We store all your error information on the DamnIT servers.  This includes snapshots of your page's 
	HTML, which could contain things we shouldn't see, like bank account numbers.  For apps with sensitive 
	information, this could rightly be a cause of concern.</p>
	
	<p>DamnIT will shortly include an option to not save the HTML content on the DamnIT server.  
	Until then, we promise we aren't evil and will never read your HTML.</p>
	
	<h4>JavaScript concerns</h4>
	
	<p>Error information is sent from your site's domain to damnit.jupiterit.com.   
	The technique used to allow this cross domain communication involves loading a script tag and 
	tacking the data on to the end of the url like this:</p>
	
	<pre><code>&lt;<span class='html_key'>script</span> type="text/javascript" 
   src="https://damnit.jupiterit.com/errors.json?error%5Bsubj..."&gt;&lt;/<span class='html_key'>script</span>&gt;</code></pre>

	<p>The server saves the objects and sends back JavaScript like this:</p>
	
	<pre><code>ApplicationError.createCallback({<span class='attribute'>error</span>: "https://damnit.jupiterit.com/errors/1833", 
   <span class='attribute'>id</span>: 1833, <span class='attribute'>status</span>: 201})</code></pre>
	
	<p>The obvious problem is we could technically send back any JavaScript here.  To paint it in 
	the most diabolical way possible, if your user's bank account number is on the page, the script 
	could find it and send it to our servers.</p>
	
	<p>In the short term future there are plans to replace the current method with 
	<a href='http://www2007.org/program/paper.php?id=801'>Subspace</a>, a method for secure 
	cross-domain communication.  Without this method, DamnIT, Google Analytics, and any other 
	remotely loaded JavaScript should never be used unless you trust the vendor completely.  
	We promise we're not evil.</p>

